BBS in a Box 5/BBS in a Box -Volume V (BBS in a Box) (April 1992).iso/Files/Prog/T/ThinkC5.0.2 Update.cpt/About THINK C 5.0.2

Text File | 1992-01-09 | 25.7 KB | 676 lines | [TEXT/ttxt]

ABOUT THINK C 5.0.2
===================
Copyright © 1992 Symantec Corporation. All rights reserved.
January 9, 1992
Font: Geneva 12

INTRODUCTION
=============
THINK C 5.0.2 corrects some problems with debugging programs on a
Macintosh Quadra and corrects some other problems in THINK C 5.0.

This document has five sections:

    •  UPDATING THINK C tells you how to run “THINK C -> 5.0.2” to
        update your copy of THINK C.

    •  WHAT THIS UPDATE FIXES lists the most important bugs that
        this update fixes.

    •  LAST MINUTE CHANGES lists some last minute changes and
        corrections to the THINK C User Manual and Standard Libraries
        Reference. This section contains much of the information in the
        READ ME file on your THINK C 5.0 disk, in addition to some more
        recent information.

    •  TECH TIPS answers some common questions that people ask
        our Technical Support staff. When you have a problem with
        THINK C, use this section along with Appendix B,
        “Troubleshooting,” to try to find a solution. And when you
        port a program from THINK C 4.0 to THINK C 5.0, use this
        section along with Appendix A, “What’s New,” for some helpful
        hints.

    •••••••••
    IMPORTANT
    •••••••••
        Some copies of the Object-Oriented Programming Manual have
        a misprint: page 313 is a duplicate of page 321. To get a copy of
        the correct 313, you need to use the THINK Class Library 1.1.1
        update.

UPDATING THINK C
=================
This update transforms your existing THINK C 5.0 application to THINK C
5.0.2. You will run the patch program “THINK C -> 5.0.2” and then replace
your debugger.

    •••••••••
    IMPORTANT
    •••••••••
        The partition size for THINK C -> 5.0.2 is set to 1 Mb (megabyte).
        If you have only 1 Mb of RAM, you’ll need to set the partition size
        to 650K. In the Finder, select the THINK C -> 5.0.2 application,
        choose Get Info…, and edit the Current Size field in the Get
        Info… dialog. If you set the partition below 650K, the application
        may quit with error ID = -108.  Your THINK C application isn’t
        damaged, and you can run the update program again with a
        larger partition.

    1. Make sure that you have your original THINK C application.
        You won't need it for this update, but you should make
        sure that you have a backup in case the update fails. Do not
        patch your original master disk.

    2. Double-click on the patch program "THINK C -> 5.0.2" to
        launch it. Click on the Update THINK C button to continue.

    3. Find your existing copy of THINK C in your THINK C Folder.
        Select it and click on the Patch button.

    4. If the patch was successful, you'll get a confirmation.

    5. Replace your THINK C Debugger 5.0 with the THINK C 5.0
        Debugger included with the upgrade.

    6. Recompile all the files in your projects to make sure they
        take advantage of the changes. To recompile a project, open
        it in THINK C, choose Remove Objects from the Project menu,
        and choose Bring Up To Date from the Project menu.

WHAT THIS UPDATE FIXES
=======================
THINK C 5.0.2 corrects some problems with debugging programs on a
Macintosh Quadra and corrects some other problems in THINK C 5.0.
This section describes the most significant bugs that THINK C 5.0.2 fixes.
It contains these parts:

•  “The Environment” describes what’s fixed in the THINK C
    environment.
•  “The Debugger” describes what’s fixed in the THINK C Debugger.
•  “Optimizations” describes what’s fixed in THINK C’s global optimizer and
     other optimizations.
•  “Object-Oriented Programming Extensions” describes what’s fixed in
    THINK C’s object-oriented programming extensions.
•  “Compiler and Linker” describes what else is fixed in THINK C‘s compiler
    and linker.

The Environment
---------------
•  When you’re running System 7.0 in 32-bit addressing mode, these features
    now work correctly:
        √ The “Grep” option in the Find… dialog.
        √ Using the Browser to look up a method or class definition.

•  Some utilities that add features to the THINK C 5.0 editor will not
    work with THINK C 5.0.2. Contact the author of the utility for a new
    version.

•  The Get Info… dialog doesn’t truncate the last character of the JUMP table
    size.

•  In the Options… dialog, the Copy button now works correctly.

•  In the Set Project Type… dialog, five-digit numbers now fit in the
    Partition field. Also, the dialog will not let you enter values greater
    than 32767 in the Partition field.

•  The Size Flags menu in Set Project Type… dialog  contains a new option:
    Use TextEdit Services. Set this bit if your application lets the user use
    inline input to enter text in a script system that uses ideographs.

• The Browser does not combine the method lists for classes that have
   similar names. Also, it no longer places method menus off the screen on
   some monitors.

The Debugger
------------
•  The debugger works correctly on a Macintosh Quadra.

•  In a Data window, you can enter a value greater than 0x7FFFFFFF for a
    integer.

•  You will not crash the debugger by selecting Go soon after it’s launched.

Optimizations
-------------
•  The “Suppress redundant loads” option is more careful when choosing to
    suppress a load.

•  The “CSE elimination” option is more careful when deciding
    whether to eliminate common sub-expressions in switch expressions.

•  The “Induction variable elimination” option is more careful when
    deciding whether an expresion is an induction variable.

•  The “CSE elimination” and “Register coloring” options are more careful
    when optimizing statements with the operators && or ||.

•  The nooptimize pragma directive disables more optimizations. In addition
    to disabling the global optimizer, it also turns off automatic register
    assignment. For more information on the nooptimize pragma directive,
    see “The pragma nooptimize directive” on page 195 in THINK C User
    Manual.

Object-Oriented Programming Extensions
-------------------------------------
•  THINK C now flags as an error a static member function that references
    a non-static member of a class without an object pointer.

•  Calling a virtual static method works correctly.

Compiler and Linker
------------------
•  There is now a limit of 256 segments per project. Previously, there was
    a limit of 128 segments per project.

•  You do not get the incorrect error message “internal error: Bad ZREF,” if
    the linker encounters an error while building your program.

•  Using the Separate STRS option does not crash THINK C.

•  In a link map, offsets for all entry points in the main segment are
    correct.

•  If you use typedef to define a type as void and declare something with
    that type, you do not get the error message “illegal use of void”.

•  If there are several #define statements before a precompiled header,
    THINK C does not generate an internal compiler error.

•  THINK C now generates an error message if you try to precompile a
    header that #defines something before #include’ing a precompiled
    header.

•  THINK C now correctly stores the size of array types declared in
    precompiled headers.

•  If a macro and a type have the same name, and you use the name to
    declare a variable, THINK C does not give you the incorrect error message
    “invalid declaration.”

•  A multi-segment code resource, driver, or desk accessory built with
    THINK C works correctly if it is unlocked and moves in memory.

•  When assigning one struct to another, the code THINK C generates now
    works correctly if the source struct is cached in an MC68040 data
    register.

•  The FNEG.X instruction generates correct code when you use it with a
    single floating-point register argument. Previously, for example,
    “FNEG.X FP0” generated code for “FABS.X FP0”.


LAST MINUTE CHANGES
====================
This section lists some last minute changes and corrections to the THINK C
User Manual and Standard Libraries Reference. It contains much of the
information in the READ ME file on your THINK C 5.0 disk, in addition to some
more recent information.

Welcome
--------
• If you have only one megabyte of RAM, you cannot compile projects that
   use MacHeaders. Instead, try to create a smaller precompiled header
   that includes only those header files you need. For more information, see
   “Editing the MacHeaders file” on page 165. You can compile projects that
   use the ANSI library with one megabyte.

Installing THINK C 5.0
--------------------
• On page 20, step 4 should refer you to Figure 2-2, not 2-1.

• On page 21, the folder is shown in Figure 2-3, not 2-1.

Tutorial: Hello World
-------------------
•  On page 34, the error message in Figure 3-7 is incorrect and should
    be “can’t open file ‘stdio.h’.” And in the first complete sentence on page
    35, the folder THINK C can’t find is the C Libraries folder.

Tutorial: MiniEdit
----------------
•  The first paragraph on page 49 tells you to click the wrong button. You
    should click on the Done button, not the Cancel button.

•  On pages 55 and 56, the Set Project Type… dialog in Figures 4-14 and
    4-15 probably doesn’t match yours. The default value for the SIZE Flags
    field is 0000, and not 0800. The project works correctly with either
    value.

•  On page 57,  the first sentence of the section “Using a Resource File” is
    incorrect. You didn’t copy the MiniEdit Folder from disk THINK C 4.
    Instead you installed it with the self-extracting archive “THINK C 5.0
    Demos.sea,” according to the instructions in Chapter 2, “Installing
    THINK C 5.0.”

Tutorial: Bullseye
-----------------
•  On page 68, Figure 5-11 shows a hollow arrow pointing at BeginUpdate().
    If you follow the instructions up to here, you’ll actually see a solid
    arrow pointing at EndUpdate().

The Project
-----------
•  In THINK C 5.0.2, the Size Flags menu in Set Project Type… dialog
    contains a new option: Use TextEdit Services. Set this bit if your
    application lets the user use inline input to enter text in a script
    system that uses ideographs.

Files & Folder
-------------
•  There are some restrictions on once-only headers (#pragma once).
    √  #Pragma once case sensitive. For example, if you include a file once
        with the statement “#include <stdio.h>” and later with the statment
        “#include <StdIO.h>”, THINK C will include it twice.
    √  #Pragma once doesn’t distinguish between files included with <...>
         and "...". For example, say you have two header files named xyz.h, one
         in the THINK C tree and one in the project tree. If you include one with
         “#include <xyz.h>” and another with “#include "xyz.h"”, THINK C will
         not include the second file.

The Compiler
-------------
•  The THINK C compiler and optimizer use MultiFinder memory. If you get an
    “Out of Memory” error, quit your other running applications to increase
    the amount of MultiFinder memory available.

•  The optimizer can take a long time to optimize extremely large and
    complex functions (typically, more than 10 pages of dense code).

 •  In THINK C 5.0.2, the nooptimize pragma directive does more. In addition
     to disabling the global optimizer, it also turns off automatic register
     assignment and honors register declarations. For more information on
     the nooptimize pragma directive, see “The pragma nooptimize directive”
     on page 195.

•  In THINK C 5.0.2, there are two new options for the options pragma
    directive. You cannot change these options within a function. For more
    information on the options pragma directive, see page “Accessing Option
    Settings in You Code” on page 195.

    √ class_names: If this option is off, THINK C does not generate class
        names in the runtime data structures for classes and you cannot use
        the new_by_name() or class_name() functions. Turning this option
        off can significantly reduce the size of your global data if you
        use very long class names.

    √ align_arrays: You can use this to defeat the alignment of even-length
        char arrays within structs. For example,

            struct S {
                char f1;
                char f2[7];
                char f3;
                char f4[8];
                char f5;
            };

        Normally, THINK C allocates the member f4 on an even boundary and
        inserts a pad byte between f3 and f4. The entire struct occupies
        20 bytes. If the align_arrays option is off, THINK C allocates f4 on an
        odd boundary and doesn’t insert a pad character. The struct occupies
        only 18 bytes.

The Assembler
--------------
•  The note on page 270 needs some explanation. When you write a
    function with in-line assembly and you declare that function pascal,  you
    need to return the function’s value in a return statement outside the
    assembly block. Don’t put the return value into D0 yourself. For example,
    use this:

            pascal int foo (void)
            {
                asm {
                    . . .
                }
                return 1;
             }

    instead of this:

            pascal int foo (void)
            {
                asm {
                    . . .
                    move.w     #1, D0
                }
             }

    Also note that you cannot return a value from an assembly block.
    In an assembly block, you can use a return statement only if it does not
    return a value. For example, this code fragment causes an error:

            pascal int foo (void)
            {
                asm {
                    . . .
                    return 1    // NO! Cannot return a value from
                }                   // within an asm block
             }

•  In THINK C 5.0, you need to write multi-line assembly language macros
    differently than with earlier versions of THINK C. For example, this
    multi-line macro causes an error in THINK C 5.0:

        #define LongMult(r, s1, s2) \
            asm {  \
                move.w  s1, d0  \
                muls  s2, d0  \
                move.l  d0, r \
            }

        void foo(void)
        {
            int a, b;
            long d;

            LongMult(d, a, b)    // Syntax error
            . . .
        }

    Multi-line assembler macros cause errors because the THINK C 5.0
    preprocessor expands the macro as one long line, like this:

        asm { move.w s1, d0  muls s2, do  move.l d0,r }

    The inline assembler doesn’t recognize the expansion as valid assembly
    language. You can define the macro like this:

        #define LongMult(r, s1, s2) \
            asm { move.w  s1, d0 } \
            asm { muls  s2, d0  } \
            asm { move.l  d0, r }

    Or you can define LongMult as just the assembly language statements,
    without enclosing them in asm { . . . }, like this:

        #define LongMult(r, s1, s2) \
            move.w  s1, d0  \
            muls  s2, d0  \
            move.l  d0, r

    And then use the macro like this:

        void foo(void)
        {
            int a, b;
            long d;

            asm {
                LongMult(d, a, b)
            }
        . . .
        }

•  On page 267, there’s an error in the section “C function entry.” It
    incorrectly states how THINK C handles a char-sized argument. The last
    two paragraphs in that section should read:

        All arguments occupy an even number of bytes on the stack.
        If there is no prototype for a char-sized argument, it is placed
        in the low byte of an int, which may be 2 or 4 bytes, depending
        on your option settings.

        If there is a prototype for a char-sized argument, it is placed
        in the high byte of a short.

•  On page 270, Figure 13-3 is incorrect. The positions of arg-1 and arg-N
    should be reversed, like this:

               -------------------------------
                 Space for return value (if any)
               -------------------------------
                 arg-1
               -------------------------------
                 . . .
               -------------------------------
                 arg-N
               -------------------------------
       SP->   return address
               -------------------------------

    The text above Figure 13-3 is correct.

The Debugger
------------
•  To stop the debugger from saving the current session, hold down the
    Option key as you exit the debugger.

•  To make the debugger display the source and data window in their
    default positions, hold down the Shift key as you enter the debugger.

•  To stop the debugger from restoring saved breakpoints and data
    expressions hold down the Option key as you enter the debugger.

•  Do not step into Macintosh Toolbox routines OpenPicture(), Open Poly(),
    OpenRgn(). Your machine could crash.

The Profiler
-----------
•  The instructions in the last paragraph of  “Changing which timer to use”
    on page 285 are incorrect. They should read:

        To create a profile library that uses the tick counter, follow
        these steps:
        1.  In the Finder, create a new copy of the profile project and
             give it a new name, like tick profile.
        2.  Open the new project with THINK C.
        3.  Choose Options… from the Edit menu.
        4.  Select Prefix from the pop-up menu in the Options…  dialog.
        5.  Comment out the line that defines _VIATIMER_. It should
             look like this: “/*  #define _VIATIMER_  */”.
        6.  Click OK.
        7.  Choose the Compile command to recompile the file.

oConv
------
• oConv can convert most reference records, despite what it says in the
   section “Conversion Limits” on page 294. It can convert most records
   from high-level languages and many from assembly language. Here are
   some types of references it cannot convert:
   √  32-bit relative references generated by the -m switch in the MPW C
        compiler
   √  32-bit relative references from assembly language
   √  16-bit data-to-code or data-to-data references in assembly language.

   oConv can convert the reference records created by the examples on
   page 294.

•  In the section “Converting Large .o Files,” the dumpobj command line on
    page 292 is incorrect. It should read:

        dumpobj OFILE.o -d -h -i -n > OLIST.txt

    And before you execute the replace command, the file OLIST.txt must be
    in an MPW window.

Standard Libraries Reference
--------------------------
•  On pages 208 and 209, the return value for the “isxxxx” family of
    functions (isalnum(), isalpha(), etc.) is wrong.  The second sentence in
    the second paragraph should read:

        It returns non-zero if c is a member of the category,  and
        0 (zero) value if c isn’t.

    And the table in the section “Returns” should read:

        If c is…                           The function returns…
        in the category               non-zero
        not in the category         0 (zero)

•  The example for printf() on page 238 should be

        #include <stdio.h>

        main()
        {
            printf ( "pi = %7.5f", 3.141593 );
        }

•  In the example for free() on page 181, the typedef should be

        typedef struct {
            int a, b;
        } Foo, *FooPtr;


TECH TIPS
=========
THINK C has many new features and enhancements that help you improve
your code.  Two changes in  THINK C 5.0 affect existing programs and
programs that you write in the future. The first change is that THINK C 5.0
conforms the ANSI standard. The second change is that THINK C now uses
the same Macintosh Toolbox interface files that Apple provides, and these
files contain more type-checking information than the built-in interfaces
in earlier versions of THINK C.

Though these changes in the THINK C development environment may mean
some changes to your existing programs, these programs will be easier to
maintain and more bug-free.

MacHeaders uses Apple’s interfaces
--------------------------------
The MacHeaders file that comes with THINK C 5.0 contains the interfaces for
the most common Macintosh Toolbox routines. This MacHeaders file is
precompiled with the "Check pointer types" option off, so all pointer types
in function prototypes are treated as generic pointers of type void *. If you
want stricter type checking for Macintosh Toolbox routines, follow the
instructions in Mac #includes.c to turn the stricter checking on.

Using stricter type-checking means that you need to cast parameters to
all Macintosh Toolbox routines, even the common ones like HLock() and
HUnlock(). The additional work pays off when THINK C catches an attempt to
pass a variable of the wrong type to a Toolbox routine.

Prototype Helper helps convert programs
-------------------------------------
The THINK C 5.0 package includes a tool called Prototype Helper to help you
convert your programs to the new ANSI standard. Prototype Helper creates
extra header files that contain the prototypes for all the functions in your
program files. Prototype Helper also converts old-style function definitions
to new-style ANSI function definitions. Many programmers report that
Prototype Helper helped them discover subtle problems that have hidden in
programs for months.

Prototype Helper uses a heuristic to convert your files, and may not always
do what you expect. Since it alters your files in place, be sure to keep a
backup of your files until you’re confident your converted files work
properly.

Function pointer types are more strictly enforced
---------------------------------------------
THINK C 5.0 is much stricter about function pointer types than earlier
versions of THINK C.  In older versions, THINK C ignored the parameters to a
function pointer. For example, THINK C 4.0 treated both of these types
identically:

    typedef int (*SomeProcPtr)();
    typedef int (*OtherProcPtr)(char);

THINK C 5.0 treats these two declarations as distinct types. It distinguishes
function pointer types by parameters as well as return value. THINK C 5.0
also allows the use of the keyword pascal as part of the function pointer
type.

This change affects programs that use the type ProcPtr as a generic pointer.
For example, in THINK C 4.0, you could write this:

    ProcPtr fp;
    (*fp)(1, 2L, 3);

In THINK C 5.0, this function pointer needs an explicit type. You can cast it
like this:

    ((void (*)(short, long, short)) fp) (1, 2L, 3);

Or, even better, you can define a type first:

    typedef void (*ShortLongShortFnPtr)(short, long, short);

    ShortLongShortFnPtr fp;

    fp(1, 2L, 3);

Note that the function pointer does not need to be dereferenced to perform
the call. The compiler does that for you.

short * and int * are not the same type
-----------------------------------
By default, the type short and the type int are the same size: 16 bits.
However, they are not the same type. The difference is particularly apparent
in functions that take pointers to shorts and pointers to int. For example:

    void f(short *p)
    {
       ...
    }

    void g(void)
    {
       int j;

       f(&j);  // ERROR: types are incompatible
       f((short *)&j);  // OK
     }

Note that none of the Macintosh Toolbox routines take ints as parameters.
They take either shorts or longs.

_fp1() and _elems1() are internal SANE routines
-------------------------------------------
If you get an error message about a function called _fp1() or _elems1(),
don't panic. These are the compiler's name for the SANE routines that
implement the high-level SANE call on the highlighted line. You may get this
error if you're using SANE, and if you try and pass a variable of type double
to a SANE routine that expects an extended. For example, the sqrt() function
below expects its argument to be of type extended.

    #include <SANE.h>
    ...
    extended x;
    x = sqrt((double) 123 / 4);

To see exactly how the _fp() function is called, use the Preprocess command
in the Source menu.

Even-sized arrays are now even-word aligned
-----------------------------------------
In some cases, THINK C 5.0 packs binary data differently than earlier
versions. If you have a structure that describes the format of binary data,
check whether the fields match up correctly in the new version. THINK C 5.0
aligns even-length arrays on even word boundaries and introduces a pad byte
if necessary. For example, in THINK C 4.0 this structure would be 12 bytes
long:

    struct foo {
        char x;
        char y[10];
        char z;
    };

The compiler would place the field y immediately after the field x. So y ends
up on an odd word boundary.

In THINK C 5.0, the same structure takes up 14 bytes. In order to align the
field y, the compiler places a pad byte between x and y. At this point, the
field z is placed at an odd address, making the structure's length 13 bytes.
Both THINK C 4.0 and THINK C 5.0 compilers will make sure that a structure
is an even length, so it is padded out with one more byte at the end.

To make sure that the structure is the same size in THINK C 5.0, make the
array odd-sized, and add the last element of the array as a field just after
the array. Since THINK C doesn't enforce array bounds checking, you can use
this declaration the same way as you used the previous one:

    struct foo {
        char x;
        char y[9];
        char y10;     // introduce dummy name
        char z;
    };

To get the old behavior, turn off the align_arrays pragma directive
described earlier in this document.